/*********************************************************************************
    This software is created under the term GNU General Public License.
    You should have received a copy of the GNU General Public License.
    If not, write to the Free Software Foundation, 59 Temple Place - Suite 330,
    Boston, MA 02111-1307, USA.

list_cir:
    a implement of list, using data structure circular list. it is not a
    part of interface, but a part of implement of interface list. you
    can use it through interface list.

author: xiangyun.kong(lo-sor@hotmail.com)
create: 2-26-2011

changes:

**********************************************************************************/

#ifndef __clib_list_cir_h__
#define __clib_list_cir_h__

#include <std.h>
#include <inttype.h>

/// double linked circular list
typedef struct _list_cir_node
{
    void* val;
    struct _list_cir_node* next, *pre;
} list_cir_node, *ltc_iterator;

typedef struct _list_cir
{
    list_cir_node *head;
    list_cir_node *tail;
    // the size shows the real count of items saved in the list
    // (it is not the count of node)
    int32 size;
} list_cir ;

/// create a new list
list_cir* ltc_create();
/// destroy an existed list
void ltc_destroy( list_cir* _lt );
/// get the count of datas in the list
int32 ltc_size( list_cir* _lt );

/// push data to the back of the list
void ltc_pushb( list_cir* _lt, void* _val );
/// push data to the front of the list
void ltc_pushf( list_cir *_lt, void *_val );
/// insert a new data to the list, behind the iterator
ltc_iterator ltc_insert( list_cir *_lt, ltc_iterator _it, void *_val );
/// insert a new data to the list, at the pos-th position
/// 0 <= _pos < ltc_size()
ltc_iterator ltc_insertp( list_cir *_lt, int32 _pos, void *_val );

/// get the value of iterator
void* ltc_val( ltc_iterator _it );
/// get the pos-th data in the list
void* ltc_get( list_cir *_lt, int32 _pos );
/// get the data at the front of the list
void* ltc_front( list_cir *_lt );
/// get the data at the back of the list
void* ltc_back( list_cir *_lt );
/// get the first iterator
ltc_iterator ltc_begin( list_cir *_lt );
/// get the last position, which is next to the last data(insertion 
/// place), of the list
ltc_iterator ltc_end( list_cir *_lt );
/// get the next to the iterator
ltc_iterator ltc_next( ltc_iterator _it );
/// get the previous to the iterator
ltc_iterator ltc_pre( ltc_iterator _it );
/// get the first iterator which data matches the key.
/// fun( _key, ltc_val(iterator) ) == 0 means the iterator matches
/// the key
ltc_iterator ltc_find( list_cir *_lt, void *_key, compare _fun );

// the following functions will delete data from list
// {3 delete begin

/// list pop front
void* ltc_popf( list_cir* _lt );
/// list pop back
void* ltc_popb( list_cir *_lt );
/// remove the iterator( and it's data from list )
/// return the data
void* ltc_remove( list_cir *_lt, ltc_iterator _it );
/// remove the pos-th data from the list
/// return the data
void* ltc_removep( list_cir *_lt, int32 _pos );

// delete finished 3}

// sort ascend the list.
void ltc_sort( list_cir *_lt, compare _fun );

#endif // __clib_list_cir_h__
